home *** CD-ROM | disk | FTP | other *** search
/ Hottest 6 / Hottest 6 (1996)(PDSoft)[!].iso / software / programming / c / cat2h / cat2h.doc < prev    next >
Text File  |  1978-11-24  |  6KB  |  178 lines
  1.  
  2.                       **********************************
  3.  
  4.                             Cat2H 1.0b
  5.  
  6.                             Catalog To C Header File
  7.  
  8.                             (c) 1992 Nico François
  9.  
  10.                       **********************************
  11.  
  12.  
  13. Preface
  14. =======
  15.  
  16. The programs and files in this distribution are freely distributable, but are
  17. also copyright (c) Nico François.  They may be freely distributed as long as
  18. no more than a nominal fee is charged to cover time and copying costs.
  19.    No commercial usage is permitted without written permission from the
  20. author.  Everything in this distribution must be kept together, in original
  21. unmodified form.
  22.    The above is generally known as freeware.
  23.  
  24.    If you have suggestions or remarks about this program, or if you find
  25. any bugs, please let me know.
  26.  
  27.    Contacting the author:
  28.  
  29.      Fido:  2:292/603.10 (Nico Francois)
  30.  
  31.      UUCP:  Nico.Francois@p10.f603.n292.z2.FidoNet.Org
  32.  
  33.      Mail:  Nico François
  34.             Corbielaan 13
  35.             B-3060 Bertem
  36.             BELGIUM
  37.  
  38.    If you can please use e-mail.  That way you'll stand a much better chance
  39. of getting a reply quickly.
  40.  
  41.    Cat2H (naturally?) requires at least Kickstart 2.0 to run.
  42.  
  43.  
  44. Contents
  45. ========
  46.  
  47. 1. Introduction
  48.  
  49. 2. Usage
  50.  
  51. 3. Example
  52.  
  53.  
  54. 1. Introduction
  55. ===============
  56.  
  57.    Cat2H is a program I wrote because I was a bit annoyed with the way CatComp
  58. (© Commodore) translated catalog files into C header files.  CatComp will
  59. create a header file with defines for the ids and for the strings seperately,
  60. followed by a table which is used to find the string associated with a
  61. particular id.  Hmmm.  Now that could be done more efficiently, couldn't it!?
  62.  
  63.    Cat2H will translate a catalog file into a header which only holds one
  64. define for a string (and _no_ table).  Cat2H will build the string so the
  65. first two characters will hold the string ID, followed by the actual string.
  66. This reduces the overhead from 8 bytes (2 longs) to 2 bytes (1 word).  So you
  67. only have 25% of the overhead CatComp gices you!  You also don't have the
  68. problem of having to look up the string in a table, resulting in a speed gain
  69. as well (especially if you have a lot of strings)!
  70.  
  71.    Cat2H has only one limitation: it limits you to 65536 strings, the ID may
  72. not be larger than that (it must fit in one word).  Shouldn't pose much
  73. problems, unless maybe you're writing an electronic dictionary :-)
  74.  
  75.  
  76. 2. Usage
  77. ========
  78.  
  79.    Cat2H can only be used from the Shell or CLI.  Use it like this:
  80.  
  81.    Cat2H <catalog.cd> <header.h> [NOID]
  82.  
  83.    For example: 'Cat2H reqtools.cd catalog.h'
  84.  
  85.    This will translate the catalog description file 'reqtools.cd' into the C
  86. header file 'catalog.h'.
  87.  
  88.    The NOID option will cause Cat2H to leave out the string IDs.  This means
  89. you can no longer use the strings for localizing.  This might be useful if you
  90. wish to compile a version of your program that can't be localized.
  91.    Suppose you had a function 'GetString (str)' to localize a string.  If you
  92. use Cat2H with the NOID option and put '#define GetString(x) x' in your source
  93. you will be able to compile your program in a localized and a non-localized
  94. version.
  95.  
  96.  
  97. 3. Example
  98. ==========
  99.  
  100.    Take for example this (small) catalog description file:
  101.  
  102.    -----------------------------------------------------------------------
  103.    MSG_OUTOFMEM (1//)
  104.    Out of memory!
  105.    MSG_ABORT (//)
  106.    Abort
  107.    -----------------------------------------------------------------------
  108.  
  109.    Will be translated by Cat2H to:
  110.  
  111.    -----------------------------------------------------------------------
  112.    /* Header file generated by Cat2H 1.0b - DO NOT EDIT! */
  113.  
  114.    #define MSG_OUTOFMEM "\x0\x1" "Out of memory!"
  115.    #define MSG_ABORT "\x0\x2" "Abort"
  116.    -----------------------------------------------------------------------
  117.  
  118.    If you then include a function like this in your program:
  119.  
  120.    -----------------------------------------------------------------------
  121.    char *GetStr (struct Catalog *cat, char *idstr)
  122.    {
  123.       char *local;
  124.  
  125.       local = idstr + 2;
  126.       if (LocaleBase)
  127.           return ((char *)GetCatalogStr (cat, *(UWORD *)idstr, local));
  128.       return (local);
  129.    }
  130.    -----------------------------------------------------------------------
  131.  
  132.    Then you can use this function like this:
  133.  
  134.    -----------------------------------------------------------------------
  135.    NotifyUser (GetStr (MSG_OUTOFMEM), GetStr (MSG_ABORT));
  136.    -----------------------------------------------------------------------
  137.  
  138.    If you use the function NotifyUser() a lot it is much more efficient to
  139.    have it work with IDs instead of strings (calling GetStr() from inside
  140.    NotifyUser()).  This can potentionally save a _lot_ of code.  Then you
  141.    can use it like this:
  142.  
  143.    -----------------------------------------------------------------------
  144.    NotifyUser (MSG_OUTOFMEM, MSG_ABORT);
  145.    -----------------------------------------------------------------------
  146.  
  147.                                                        Enjoy.
  148.  
  149.  
  150.                                PROGRAM HISTORY:
  151.  
  152. *****************************************************************************
  153. RELEASE 1.0
  154.  
  155.     First release.
  156.  
  157. *****************************************************************************
  158. RELEASE 1.0a
  159.  
  160.     Fixed small bug: Cat2H didn't work if more than two lines of text were
  161.       used for a symbol (using the '\' "continue on next line" indicator).
  162.  
  163. *****************************************************************************
  164. RELEASE 1.0b
  165.  
  166.     Fixed small bug in startup code.
  167.     Recompiled with SAS/C 6.2.
  168.  
  169. *****************************************************************************
  170.  
  171. Cat2H 1.0b written by Nico François (Yes, Nico is my first name :-)
  172.  
  173. (c) 1992 Nico François
  174.  
  175.                                    //
  176.                        Thanks to \X/ Amiga for being the best computer ever!
  177.  
  178.